# -*- coding: utf-8 -*-
"""
核心功能模块

这个模块包含了LLM后端系统的核心组件，提供了系统的基础功能。
核心模块采用分层架构设计，确保各组件的独立性和可扩展性。

模块结构：

1. llm/ - 大语言模型客户端
   ├── base.py              # LLM抽象基类
   ├── ollama_client.py     # Ollama客户端实现
   ├── openai_client.py     # OpenAI客户端实现（可选）
   └── model_manager.py     # 模型管理器（可选）

2. retrieval/ - 检索系统
   ├── base_retriever.py    # 检索器抽象基类
   ├── hybrid_retriever.py  # 混合检索器（关键词+向量）
   ├── vector_retriever.py  # 纯向量检索器
   └── keyword_retriever.py # 纯关键词检索器

3. embeddings/ - 嵌入模型
   ├── base_embeddings.py   # 嵌入模型抽象基类
   ├── ollama_embeddings.py # Ollama嵌入模型
   └── openai_embeddings.py # OpenAI嵌入模型

4. memory/ - 记忆管理（可选）
   ├── conversation_memory.py # 对话记忆
   └── vector_memory.py       # 向量记忆

设计原则：
- 抽象化：每个子模块都有抽象基类，便于扩展
- 可插拔：不同实现可以轻松替换
- 类型安全：使用Python类型提示
- 异常处理：完善的错误处理机制
- 日志记录：详细的操作日志
- 性能优化：支持批处理和异步操作

核心接口：
- BaseLLM: 所有LLM客户端的基类
- BaseRetriever: 所有检索器的基类
- BaseEmbeddings: 所有嵌入模型的基类

使用示例：
    >>> from src.core.llm.ollama_client import OllamaClient
    >>> from src.core.retrieval.hybrid_retriever import HybridRetriever
    >>> 
    >>> # 初始化LLM客户端
    >>> llm = OllamaClient()
    >>> 
    >>> # 初始化检索器
    >>> retriever = HybridRetriever(qa_data)
    >>> 
    >>> # 使用组件
    >>> response = llm.generate("你好")
    >>> results = retriever.retrieve("问题")

扩展指南：
    要添加新的LLM提供商：
    1. 继承BaseLLM类
    2. 实现必要的抽象方法
    3. 添加相应的配置项
    4. 编写单元测试

    要添加新的检索方式：
    1. 继承BaseRetriever类
    2. 实现检索逻辑
    3. 优化性能和准确性
    4. 添加评估指标

Note:
    - 核心模块的修改需要谨慎，可能影响整个系统
    - 新增功能建议先在独立分支开发和测试
    - 保持向后兼容性，避免破坏现有API
    - 重要变更需要更新文档和示例
"""